src/praisonai-agents/praisonaiagents/agent/agent.py (4)

8472-8480: ⚠️ Potential issue | 🟠 Major

Default host='0.0.0.0' exposes the server on all interfaces.

At Line 8472, binding to all interfaces by default is a risky default for local/dev usage. Prefer loopback by default and require explicit opt-in for external exposure.

Suggested fix

-    def launch(self, path: str = '/', port: int = 8000, host: str = '0.0.0.0', debug: bool = False, protocol: str = "http") -> None:
+    def launch(self, path: str = '/', port: int = 8000, host: str = '127.0.0.1', debug: bool = False, protocol: str = "http") -> None:

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/praisonai-agents/praisonaiagents/agent/agent.py` around lines 8472 -
8480, Change the launch default to bind to loopback instead of all interfaces:
update the launch signature in agent.launch to use host='127.0.0.1' (instead of
'0.0.0.0'), update the docstring to reflect the new default and note how to
opt-in to external exposure (pass host='0.0.0.0' or an explicit external IP),
and run/update any tests or callers that relied on the old default to pass an
explicit host when external binding is required.

---

5365-5387: ⚠️ Potential issue | 🟠 Major

ephemeral() method has an incorrect return type annotation for a @contextmanager-decorated function.

The return type -> bool (line 5365) is invalid. Context manager functions that use yield should return Generator[None, None, None]. The file already imports Generator from typing, so the fix can be applied immediately.

Fix

     `@contextlib.contextmanager`
-    def ephemeral(self) -> bool:
+    def ephemeral(self) -> Generator[None, None, None]:

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/praisonai-agents/praisonaiagents/agent/agent.py` around lines 5365 -
5387, The ephemeral() context manager currently has an incorrect return
annotation "-> bool"; update its signature to use the correct generator type by
changing the return type to Generator[None, None, None] (the file already
imports Generator) so the `@contextmanager-decorated` function is properly typed;
keep the body as-is (uses self._history_lock, saved_history, and
self.chat_history) and ensure the import for Generator remains used.

---

3755-3770: ⚠️ Potential issue | 🟠 Major

llm_model return type annotation does not match actual return values.

The property at line 3755 is annotated as Optional[str], but it can return self.llm_instance (an LLM instance) or self.llm (which may also be an LLM instance). The docstring explicitly documents that it returns "LLM instance object" for two of three cases, contradicting the string-only type annotation.

Suggested fix

-    def llm_model(self) -> Optional[str]:
+    def llm_model(self) -> Optional[Union[str, LLM]]:

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/praisonai-agents/praisonaiagents/agent/agent.py` around lines 3755 -
3770, The llm_model property is annotated as Optional[str] but can return
objects (self.llm_instance or self.llm) or a string; update the signature to
reflect that (e.g., Optional[Union[str, Any]] or Optional[Union[str, BaseLLM]]
depending on your LLM base class) and adjust the docstring/type hints
accordingly so llm_model, llm_instance and llm are consistent; ensure you import
Union/Any or the appropriate BaseLLM type at the top of the module.

---

6088-6108: ⚠️ Potential issue | 🟠 Major

Public method return annotations are too narrow for actual None-returning paths.

chat() and downstream wrappers (run, execute, aexecute) can return None when execution is blocked by BEFORE_AGENT hooks, but signatures exclude None. Additionally, achat() is missing a return type annotation entirely.

Suggested fix

-    def chat(...) -> Union[str, Generator[str, None, None]]:
+    def chat(...) -> Optional[Union[str, Generator[str, None, None]]]:

-    def run(self, prompt: str, **kwargs) -> str:
+    def run(self, prompt: str, **kwargs) -> Optional[str]:

-    def execute(self, task: Any, context: Optional[Any] = None) -> Union[str, Generator[str, None, None]]:
+    def execute(self, task: Any, context: Optional[Any] = None) -> Optional[Union[str, Generator[str, None, None]]]:

-    async def aexecute(self, task: Any, context: Optional[Any] = None) -> Union[str, Generator[str, None, None]]:
+    async def aexecute(self, task: Any, context: Optional[Any] = None) -> Optional[Union[str, Generator[str, None, None]]]:

-    async def achat(self, prompt: str, temperature=1.0, ...):
+    async def achat(self, prompt: str, temperature=1.0, ...) -> Optional[Union[str, Generator[str, None, None]]]:

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/praisonai-agents/praisonaiagents/agent/agent.py` around lines 6088 -
6108, The public method chat (and its async counterpart achat plus wrappers run,
execute, aexecute) can return None when execution is blocked by BEFORE_AGENT
hooks, so update their type annotations to include None: change chat's return
type to Optional[Union[str, Generator[str, None, None]]] (or Optional[...]
equivalent), add an explicit Optional return annotation for achat, and adjust
the signatures of run, execute and aexecute to reflect Optional returns as well;
ensure imports (typing.Optional, Union, Generator) are present and keep all
other behavior unchanged.

src/praisonai-agents/praisonaiagents/agent/agent.py (5)

8472-8482: ⚠️ Potential issue | 🟠 Major

Default HTTP host should be loopback, not all interfaces.

Using host='0.0.0.0' as default makes accidental external exposure easier. Safer default is localhost with explicit opt-in for external bind.

💡 Suggested fix

-    def launch(self, path: str = '/', port: int = 8000, host: str = '0.0.0.0', debug: bool = False, protocol: str = "http") -> None:
+    def launch(self, path: str = '/', port: int = 8000, host: str = '127.0.0.1', debug: bool = False, protocol: str = "http") -> None:

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/praisonai-agents/praisonaiagents/agent/agent.py` around lines 8472 -
8482, Change the default bind address in the Agent.launch signature from
'0.0.0.0' to the loopback address '127.0.0.1' to avoid accidental external
exposure; update the function signature in launch(self, path: str = '/', port:
int = 8000, host: str = '127.0.0.1', ...) and adjust the docstring text that
describes the default host so it reflects localhost as the default and that
'0.0.0.0' is an explicit opt-in for external binding; ensure any call sites or
tests that rely on the old default are updated to pass '0.0.0.0' explicitly if
needed.

---

3683-3710: ⚠️ Potential issue | 🟠 Major

Use save/load terminology and keep store_memory as a deprecated alias.

The changed public method still uses store_memory, which conflicts with repository persistence naming conventions.

💡 Suggested migration pattern (non-breaking)

+    def save_memory(self, content: str, memory_type: str = "short_term", **kwargs) -> None:
+        """Save content in memory."""
+        if not self._memory_instance:
+            return
+        # (move existing implementation body here)
+
     def store_memory(self, content: str, memory_type: str = "short_term", **kwargs) -> None:
-        """
-        Store content in memory.
-        ...
-        """
-        if not self._memory_instance:
-            return
-        ...
+        import warnings
+        warnings.warn(
+            "store_memory() is deprecated; use save_memory() instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self.save_memory(content, memory_type=memory_type, **kwargs)

As per coding guidelines "Persistence operations should use save()/load() terminology, never store(), to maintain consistency across memory and session adapters".
Based on learnings "Public API changes require a deprecation cycle: emit DeprecationWarning for one release before breaking change".

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/praisonai-agents/praisonaiagents/agent/agent.py` around lines 3683 -
3710, Introduce a new public method save_memory(content: str, memory_type: str =
"short_term", **kwargs) that implements the same logic currently in store_memory
but preferring save_* protocol method names (save_short_term, save_long_term,
save_entity, save_episodic) and falling back to legacy add_* methods on
self._memory_instance; then change store_memory to be a thin deprecated wrapper
that emits a DeprecationWarning and forwards to save_memory with the same
arguments. Ensure you reference self._memory_instance and check hasattr for
save_* then add_* method names when dispatching.

---

3755-3770: ⚠️ Potential issue | 🟠 Major

Fix llm_model return type annotation to match actual return values.

The property at line 3755 is typed as Optional[str], but it returns self.llm_instance (an LLM object) or self.llm (which can be either a string or LLM instance). Type checkers will incorrectly assume the return is always a string.

Fix

 if TYPE_CHECKING:
     from ..task.task import Task
+    from ..llm.llm import LLM
     from .handoff import Handoff, HandoffConfig, HandoffResult
     from ..rag.models import RAGResult, ContextPack
     from ..eval.results import EvaluationLoopResult

-    def llm_model(self) -> Optional[str]:
+    def llm_model(self) -> Union[str, "LLM"]:

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/praisonai-agents/praisonaiagents/agent/agent.py` around lines 3755 -
3770, The llm_model property is annotated as Optional[str] but returns objects
(self.llm_instance or self.llm) or a string default; update the return type on
llm_model to reflect both LLM instances and strings (e.g., Optional[Union[str,
Any]] or Optional[Union[str, BaseLLM]] depending on available types), and ensure
imports (typing.Union or typing.Any or the concrete BaseLLM type) are added if
needed; keep the existing logic using self.llm_instance, self.llm, and the
default "gpt-4o-mini" unchanged.

---

7440-7542: ⚠️ Potential issue | 🟠 Major

Update return type annotation to include all actual return branches.

The start() method signature declares Union[str, Generator[str, None, None]], but the implementation returns AutonomyResult in autonomy-enabled branches and can return None from _start_with_planning().

Suggested fix

if TYPE_CHECKING:
    from ..task.task import Task
+   from .autonomy import AutonomyResult
    from .handoff import Handoff, HandoffConfig, HandoffResult
    from ..rag.models import RAGResult, ContextPack
    from ..eval.results import EvaluationLoopResult

 class Agent:
-    def start(self, prompt: Optional[str] = None, **kwargs) -> Union[str, Generator[str, None, None]]:
+    def start(self, prompt: Optional[str] = None, **kwargs) -> Union["AutonomyResult", str, Generator[str, None, None], None]:

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/praisonai-agents/praisonaiagents/agent/agent.py` around lines 7440 -
7542, The start() return type annotation is incomplete: it can return an
AutonomyResult (when autonomy_enabled caller/iterative branches use
run_autonomous or return AutonomyResult) and may return None (e.g., from
_start_with_planning()), so update the signature to include those types (e.g.,
Union[str, Generator[str, None, None], AutonomyResult, None] or
Optional[Union[str, Generator..., AutonomyResult]]), and add any needed typing
imports or forward references; adjust the start method signature and any related
type hints (references: start, run_autonomous, _start_with_planning,
AutonomyResult) so the annotation accurately reflects all actual return
branches.

---

6088-6110: ⚠️ Potential issue | 🟠 Major

Harden call sites against None returns from chat().

The method signature (-> Optional[str]) is not defensive—multiple code paths explicitly return None: hook blocks (line 6161), validation failures (lines 6356, 6361, 6364), and LLM errors (lines 6445, 6468, 6489, etc.). Current call sites are inconsistent: some guard with if response: or str(response) if response else "", but others assume strings (e.g., len(response) at test_real_key_smoke.py:73, 100; _clean_commit_message(response) at main.py:3739). Since these None returns are legitimate (hook blocks and validation failures cannot safely return strings), consumers must be hardened rather than the contract tightened. Add None checks before all string operations or fallback behavior.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/praisonai-agents/praisonaiagents/agent/agent.py` around lines 6088 -
6110, Agent.chat has an Optional[str] return and legitimately returns None in
several paths; update all callers that treat the result as a string (e.g., uses
of len(response), string methods, or passing into _clean_commit_message) to
handle None safely by checking for None before any string operations and
providing a clear fallback (e.g., treat None as empty string "" where
appropriate, skip processing, log and return early, or raise a clear error).
Search for usages of Agent.chat/response in code (examples: calls in
test_real_key_smoke tests and the call to _clean_commit_message in main.py) and
wrap them with if response is None: <fallback action> or use a local
safe_response = response or "" before invoking len(), .startswith(),
_clean_commit_message(), or other string-only functions.